Building a custom integration

Supported in:

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.

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
            ))

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.

buildingcustintegration3

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

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:

buildingcustintegration5

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.

buildingcustintegration9

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.