Building a custom integration

Supported in:

Google SecOps SOAR

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 tutorial, you 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

1. In the left navigation, navigate to Response > IDE.
2. Click Create New Item and select Integration.
3. Enter a name and click Create.

The integration will be created and listed on the left hand side with a settings icon to the right that designates it as a custom integration.

Clicking settings will bring up the integration settings where the icon, description, Python dependencies, and integration parameters can be defined.

Note: 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:

1. In the IDE, click Create New Item and select Manager.
2. Select the Armis integration, and name the manager.
   
3. Edit the following script.

import requests

class ArmisManager:
    def init(self, api_root, api_token):
        self.api_root = api_root
        self.api_token - api_token
        self.session = requests.session
        self.session.headers = {"Accept": "application/json"}

    def auth(self):
        endpoint = "{}/api/vi/access_token/*"
        params = {"secret_key" : self.api_token}
        response = self.session.post(endpoint.format(self.api_root), params=params)
        self.validate_response(response)
        access_token = response.json()["data"]["access_token"]
        self.session.headers.update({"Authorization": access_token})
        return True

    def get_device_by_ip(self, device_ip):
        endpoint = "{}/api/vi/devices/"
        params = {"ip": device_ip}
        response = self.session.get(endpoint.format(self.api_root), params=params)
        self.validate_response(response)
        return response.json()["data"]["data"]

    @staticmethod
    def validate_response(res, error_msg="An error occurred"):
        """Validate a response

        :param res: (requests. Response) The response to validate
        :param error_msg: (str) The error message to display
        """
        try:
            res.raise_for_status()
        except requests.HTTPError as error:
            raise Exception("(error_msg): (error) (text)".format(
                error_msg=error_msg,
                error=error,
                text=error.response.content
            ))

Note: 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, Google Security Operations Marketplace configuration and the Ping action

The parameters defined in the integration settings will appear in the Google Security Operations Marketplace configuration for the integration.

After entering the correct credentials, click Save and then, click Test.

Note: 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 Google Security Operations Marketplace Integration Configuration page.

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 Google Security Operations 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.

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 Google Security Operations Marketplace

Navigate to the Google Security Operations 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 Google Security Operations 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 Google Security Operations Marketplace.