Build a custom integration

Supported in:

Google secops SOAR

This document explains how to create custom integrations inside the Integrated Development Environment (IDE) using the same structure as commercial integrations. You can find and configure custom integrations in the Google Security Operations Marketplace for various environments. You can then use them in playbooks, manual actions, and remote agents. Import and export capability is also supported, similar to other IDE items.

Create a custom integration in the IDE

You can 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 procedure.

Use case: Build a custom Armis integration

To create the custom integration in the IDE, follow these steps:

1. In the main menu, go to Response > IDE.
2. Click Create New Item and select Integration.
3. Enter a name and click Create.

The integration is now listed with the settings Settings option, indicating it's a custom integration.

Click settings Settings to display the integration settings where you can define the icon, description, Python dependencies, and integration parameters.

Note: Script dependencies are Python libraries the custom integration needs to import. Dependencies can be added as `.WHL`, `.TAR`, `.GZ`, or `.PY` files. Each integration runs in its own virtual environment, allowing you to use different library versions even if one is already installed on the system. For example, to use a different version of the requests library, download it from a trusted source such as PyPI or GitHub and add it as a script dependency. If not installed in the virtual environment, the integration falls back to the system version.

Create a custom manager

Managers are wrappers for third-party tool APIs. Although not mandatory, we recommend them for integrations that interact with external tools. Managers shouldn't import from the SDK. After creation, import them into connectors, actions, and jobs.

To create a custom manager, follow these steps:

1. In the IDE, click Create New Item and select Manager.
2. Select the Armis integration and enter a manager's name.
   
3. Edit and run 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: A manager is not required for basic actions. However, we recommend to create one when grouping small actions for data parsing and transformation.

Parameters, Google SecOps Marketplace configuration, and the Ping action

Parameters defined in the integration settings appear in the Google SecOps Marketplace configuration. The parameters include:

• API Root: The base URL for the service you're connecting to.
• API Secret: A confidential key used to authenticate your application with the service.
• Verify SSL checkbox: If enabled, verifies that the SSL certificate for the connection to the Armis server is valid.
• Run Remotely checkbox: A setting that determines whether the code or task will be executed on a remote server instead of locally. When this option is enabled, the system sends the necessary instructions and data to a dedicated server for processing.

To update the parameters, follow these steps:

1. Enter the correct credentials.
2. Click Save > Test.

Note: Always click Save after updating credentials. All third-party integrations must implement a Ping action. The Test button runs this action to validate connectivity.

If the Ping action is missing, the Test button fails and displays a red X.

Implement a Ping action

The logic of the Ping action acts like a successful authentication.

To implement a Ping action, do the following:

1. In the IDE, create a new Action in the Armis integration named Ping.
2. Use the ArmisManager auth method to verify authentication.

Enable the integration

To enable the integration, follow these steps:

1. In Response > IDE, click the Enable/Disable toggle to the ON position.
2. Click Save. A green toggle confirms success. Credentials from the Marketplace are passed to ArmisManager. If auth completes without errors, the Test button shows a green checkmark.

Use the extract_configuration_param method to import parameters from the integration configuration. Alternatively, use extract_action_param to define parameters within the action itself. However, the Ping action should always use configuration parameters, as those are tested by the Marketplace.

View custom integrations

Go to the Google SecOps Marketplace and search for the custom integration you created. If you didn't create an image during the initial configuration, the default custom image will be assigned to it. Note that Google SecOps Marketplace updates don't override or delete any custom integrations.

Export and import in the IDE

Do one of the following actions:

• To import integrations, do the following:
1. Upload a ZIP file with the correct folder structure; the integration appears in the IDE and Google SecOps Marketplace.
2. Click Import. The integration appears in both the IDE and the Marketplace.
3. The system generates a ZIP file containing the definition, scripts, and configuration. The Managers folder is not included automatically.
• To export integrations, do the following:
• Click Export to download the package.

Need more help? Get answers from Community members and Google SecOps professionals.